CSS Font-Size Keyword Converter - User Guide

What This Plugin Does

This plugin converts CSS font-size keywords like small, large, medium, etc. into em or rem units throughout your e-book. It works in three places:

1. CSS files (external stylesheets like style.css)
2. Style blocks in HTML headers (<style>...</style>)
3. Inline styles on HTML elements (<p style="font-size: small;">)

Why Convert?

Some e-readers don't handle CSS keywords consistently. Converting to em/rem units gives you more control over text sizing across different devices and ensures more predictable rendering.

What Gets Converted

The plugin converts these CSS keywords:

• xx-small
• x-small
• small
• medium
• large
• x-large
• xx-large
• smaller
• larger

What Doesn't Get Converted

The plugin leaves these alone:

• Already converted sizes (12px, 1em, 1rem, 100%, etc.)
• System keywords (inherit, initial, unset)
• Wrong properties (background-size, border-width, etc.)
• Keywords in comments or strings
• Complex shorthand with calc(), var(), etc. (automatically skipped)

Installation

1. Download the plugin ZIP file: NewUnit_v0.7.0.zip
2. Open Sigil
3. Go to Plugins → Manage Plugins
4. Click Add Plugin
5. Select the downloaded ZIP file
6. Click OK
7. Restart Sigil for the plugin to appear in the menu

Location after install:

• Plugins → Edit → CSS Font-Size Keyword Converter

Quick Start

Basic Conversion (5 Steps)

1. Open your e-book in Sigil
2. Go to Plugins → Edit → CSS Font-Size Keyword Converter
3. The plugin scans and shows files containing keywords
4. Check the boxes for files you want to convert
5. Click Apply Changes

That's it! Your keywords are now converted.

Recommended Workflow

1. Save your book in Sigil first (File → Save)
2. Run the plugin as above
3. Click Preview before applying (optional but recommended)
4. Review the changes in the preview window
5. Click Apply Changes if everything looks good
6. Test your book in an e-reader
7. Click Undo if you need to revert

Configuration

Click the ⚙ Configuration button to customize conversion settings.

Configuration Window Layout

The window has two columns:

Left Column:

• Keyword value settings
• Unit type selection (em or rem)
• Bulk setting buttons

Right Column:

• Font shorthand options (advanced)
• Backup options

Keyword Values

Each keyword can have a custom numeric value and unit:

To change a value:

1. Type a new number in the Value field
2. Select em or rem radio button
3. Click Save

Quick Actions:

• All em button: Sets all keywords to use em units
• All rem button: Sets all keywords to use rem units
• Reset Defaults: Restores original values and em units

em vs rem - Which Should I Use?

em (relative to parent):

• Size is relative to the parent element's font size
• If parent is 16px and you set 0.5em, you get 8px
• Good for components that scale together
• Can compound (nesting can make things very small or large)

rem (relative to root):

• Size is relative to the document's root font size
• More predictable across the entire document
• No compounding issues
• Generally recommended for e-books

Font Shorthand (Advanced)

By default, the plugin only converts the font-size: property:

font-size: small;  →  font-size: 0.89em;

You can optionally enable conversion of the font: shorthand property:

font: small Arial;  →  font: 0.89em Arial;
font: bold small/1.5 Georgia;  →  font: bold 0.89em/1.5 Georgia;

To enable:

1. Check "Also convert font: shorthand property"
2. Click Save

Important Notes:

• This is more complex than font-size conversion
• You'll see a preview before changes are applied
• Unsafe patterns are automatically detected and skipped
• You can choose to skip shorthand changes even after enabling

When to enable:

• Your CSS uses font: shorthand with keywords
• You've previewed and understand the changes
• You're comfortable reviewing the preview dialog

When to keep disabled:

• You only use font-size: property (most common)
• You want the simplest, safest conversion
• You're unsure about shorthand syntax

Backup Options

The plugin always keeps a memory backup for the Undo button. You can also create external backup files on your hard drive.

To enable external backups:

1. Check "Create backup copies before converting"
2. Click Browse and select a folder
3. Click Save

Backup file naming:

Original: style.css
Backup:   style_20250115_103045.css
          +- Timestamp: YYYYMMDD_HHMMSS

When to use external backups:

• Converting large books (50+ files)
• You want permanent backups outside Sigil
• You want to compare before/after files
• Extra safety for important projects

When you don't need them:

• Small books (< 10 files)
• Just using the Undo button
• Sigil's built-in checkpoints are enough

Saving and Loading Configurations

Save as Default:

• Saves current settings as your default
• These values are used next time you open the plugin
• Stored in Sigil's preferences

Save to Named Config:

• Save with a custom name (e.g., "Kindle Settings")
• Stores as a JSON file in your config folder
• Can add an optional description
• Reusable across different books

Load Named Config:

• Shows a list of all saved configurations
• Select one to load its settings
• Updates all values in the configuration window

Example use case:

1. Create "Kindle Preset" with larger text (all values +0.2)
2. Create "Kobo Preset" with standard values
3. Create "Print PDF" with rem units and specific sizing
4. Load the appropriate preset for each project

Understanding the Workflow

Step-by-Step Explanation

1. File Scanning

When you open the plugin:

1. It scans all CSS and HTML files in your book
2. Looks for font-size keywords in:
   • CSS files (.css)
   • HTML <style> blocks
   • Inline style="" attributes
3. Counts how many matches each file has
4. Shows the list with checkboxes

The list shows:

☐ style.css (CSS) - 15 match(es)
☐ chapter1.html (TEXT) - 3 match(es)
☐ chapter2.html (TEXT) - 5 match(es)

2. File Selection

Select files to convert:

• Check boxes for files you want to convert
• Use Select All to check everything
• Use Clear Selection to uncheck everything

Filter options:

• Show All: Display all file types
• Show HTML/XHTML Files: Only text files
• Show CSS Files: Only stylesheets

3. Preview (Optional but Recommended)

Click Preview to see exactly what will change:

Preview window shows:

style.css (5 changes)
--------------------------------

Line 42:
  font-size: small;           [pink background]
  font-size: 0.89em;          [green background]

Line 58:
  [SHORTHAND] font: small Arial;  [blue background, red label]
  font: 0.89em Arial;             [green background]

Color coding:

• Pink = Original CSS (font-size changes)
• Blue = Original CSS (shorthand changes)
• Red [SHORTHAND] = Identifies shorthand conversions
• Green = Converted CSS (both types)

Preview features:

• Scrollable list of all changes
• Shows line numbers
• Groups changes by file
• Copy to Clipboard button

4. Safety Checks (If Shorthand Enabled)

If you've enabled shorthand conversion, you may see up to two dialogs:

Dialog 1: Unsafe CSS Detected (if any unsafe patterns exist)

Shows patterns like:

font: calc(1em + 2px) small Arial;
font: var(--size) small serif;

These are too complex to convert safely and will be skipped (not converted).

Your options:

• Stop - Don't Make Any Changes: Abort everything, nothing changes
• Continue - Skip Unsafe Items: Proceed with conversion, skip these items

What happens to unsafe items:

• They remain exactly as they are
• They are not converted
• You must edit them manually if you want them converted

Dialog 2: Review Safe Shorthand Changes (if any safe shorthand exists)

Shows shorthand patterns that can be safely converted:

font: small Arial;
font: bold large serif;

Summary shows:

Safe font-size conversions: 15 (will be applied)
Safe shorthand conversions: 3 (review below)

These shorthand conversions have been validated as safe.
Unsafe patterns have already been filtered out.

Your options:

• Skip Shorthand - Apply Font-Size Only: Convert font-size: only, skip all font:
• Apply All (Font-Size + Shorthand): Convert both types

5. Conversion

The plugin processes your selected files:

You'll see:

Converted: style.css (15 change(s))
Converted: chapter1.html (3 change(s))

Successfully converted 18 match(es) in 2 file(s).

During conversion:

• Comments are preserved
• Line breaks are preserved
• Only the keywords change
• All other CSS remains identical

After conversion:

• The file list is disabled (grayed out)
• The Undo button becomes active
• Status shows the results

6. Undo (If Needed)

If you don't like the results:

1. Click Undo (orange button)
2. All modified files are restored to their original state
3. The file list is re-enabled
4. You can adjust settings and try again

Undo details:

• Works only in the current session
• Restores exact original content (byte-for-byte)
• Can undo even after external backup
• Once you close the plugin, undo is no longer available

Tips and Best Practices

Before Converting

1. Save Your Work

• Save your book in Sigil: File → Save
• Create a Sigil checkpoint: Edit → Create Checkpoint
• Make a backup copy of your EPUB outside Sigil

2. Test on a Copy First

• For important books, make a copy and test on that
• Verify the results in an e-reader
• Apply to the real book only after testing

3. Review Your CSS

• Check if you're using keywords or already converted units
• Look for complex font shorthand
• Note any custom CSS that might be affected

During Conversion

1. Start with Preview

• Always preview before applying to large books
• Check a few files to verify the values look correct
• Make sure shorthand conversions (if enabled) look safe

2. Convert in Batches

• For very large books (100+ files), convert in smaller batches
• Do CSS files first, then HTML files
• Easier to review and troubleshoot

3. Read the Safety Warnings

• If you see "Unsafe CSS Detected", review the list
• These items will NOT be converted
• Note them down for manual editing later

Choosing Values

Standard e-book sizes:

• Use the defaults (0.6 to 2em range)
• These approximate browser defaults
• Work well across most e-readers

Larger overall text:

• Increase all values by 0.1-0.2
• Example: small becomes 1em instead of 0.89em
• Good for older readers or accessibility

More contrast between sizes:

• Increase large/x-large/xx-large
• Decrease small/x-small/xx-small
• Creates more dramatic size differences

Custom per-keyword:

• Adjust specific keywords as needed
• Example: Keep medium at 1em but increase large to 1.5em
• Test in your target e-reader

After Conversion

1. Validate Your Book

• Use Sigil's built-in validation: Tools → Validate EPUB
• Fix any errors before exporting

2. Test in E-readers

• Test in your target devices/apps
• Check that text sizes look appropriate
• Verify no unintended changes occurred

3. Check Edge Cases

• Look at nested elements (lists within lists, etc.)
• Check tables, blockquotes, headings
• Verify footnotes and endnotes

4. Keep Your Configuration

• If you like the results, save as a named config
• Reuse for similar projects
• Document what works for your workflow

Working with Mixed Content

Already partially converted:

• Filter to see only files with keywords remaining
• Convert just those files
• Leave already-converted files unchecked

Multiple CSS files:

• You can use different configurations for different files
• Convert one batch, adjust settings, convert another
• Use named configs to switch between settings quickly

Troubleshooting

Common Issues and Solutions

"No font-size keywords found in any files"

Cause: Your book doesn't use CSS keywords, or they're already converted.

Check:

• Are you already using px, em, rem, or %?
• Are keywords only in CSS comments?
• Are you looking at the right book in Sigil?

Solution:

• If already converted, no action needed
• If using comments, the plugin correctly ignores them

"Please select at least one file"

Cause: No checkboxes are checked when you click Preview or Apply.

Solution:

• Check at least one file from the list
• Use "Select All" to check everything
• Make sure the filter isn't hiding the files you want

Backup Folder Errors

Error: "No backup folder specified"

• You enabled backups but didn't choose a folder
• Click Browse and select a folder

Error: "Folder does not exist"

• The folder was deleted or moved
• Click Browse and select a valid folder

Error: "Folder is not writable"

• You don't have permission to write to that folder
• Choose a different folder (like Desktop or Documents)
• On Mac/Linux: Check folder permissions

Error: "Path is not a directory"

• You selected a file instead of a folder
• Click Browse and select a folder

Preview or Apply Takes a Long Time

Cause: Large books with many files take time to process.

Solutions:

• Wait for completion (normal for 100+ files)
• Close other applications to free memory
• Convert in smaller batches (50 files at a time)
• Consider disabling shorthand conversion to speed up processing

Changes Don't Look Right

Problem: Converted sizes are too large or too small.

Solution:

1. Click Undo immediately
2. Open Configuration
3. Adjust the numeric values
4. Click Preview to verify
5. Apply again

Problem: Some keywords weren't converted.

Check:

• Were they in shorthand patterns? (Check if shorthand was enabled)
• Were they marked as unsafe? (Check the console output)
• Were they in the right property? (font-size: not background-size:)

Solution:

• Re-run with shorthand enabled if needed
• Manually edit unsafe patterns
• Verify the CSS syntax is correct

Undo Doesn't Work

Problem: Undo button is grayed out.

Cause: No changes have been applied yet, or you already undid.

Problem: Undo button doesn't appear.

Cause: The plugin closed before you could undo.

Solution: Use Sigil's checkpoints or reload a backup EPUB.

Plugin Crashes or Freezes

Symptoms:

• Plugin window doesn't respond
• Sigil becomes unresponsive
• No progress after clicking Apply

Solutions:

1. Wait 2-3 minutes (may be processing)
2. Check Sigil's debug log for errors
3. If truly frozen, force quit and restart Sigil
4. Report the issue with details (see Getting Help below)

Prevention:

• Convert smaller batches
• Disable shorthand if not needed
• Ensure enough free memory

Error Messages in Console

The plugin outputs messages to Sigil's debug log. To view:

• Tools → Debug → View Debug Output (or similar, depending on Sigil version)

Common messages:

"Error scanning [file]: [error]"

• Problem reading that specific file
• File may be corrupted or have encoding issues
• Other files still process normally

"Error backing up [file]: [error]"

• Problem creating backup for that file
• Check backup folder permissions
• File may be in use by another program

"Error processing [file]: [error]"

• Problem converting that file
• File may have malformed CSS
• Check the file manually in Sigil

Getting Help

If you continue to have problems:

Gather information:

1. Plugin version (currently 0.7.0)
2. Sigil version (Help → About Sigil)
3. Operating system and version
4. Specific error message or behavior
5. Steps to reproduce the problem

Check the debug log:

• Tools → Debug → View Debug Output
• Copy relevant error messages

Report the issue:

• Include all gathered information
• Attach a small test file if possible (not your entire book)
• Describe what you expected vs. what happened

Frequently Asked Questions

General Questions

Q: Will this work with all e-readers?

A: em and rem units are part of the CSS standard and widely supported. They work on:

• Amazon Kindle devices and apps
• Kobo e-readers
• Apple Books
• Google Play Books
• Adobe Digital Editions
• Most other EPUB readers

Better compatibility than CSS keywords, which vary by reader.

Q: Can I convert back from em/rem to keywords?

A: No, this plugin only converts keywords → units, not the reverse. If you want to revert, use the Undo button immediately, or restore from a Sigil checkpoint or backup EPUB.

Q: Does this modify my original EPUB file?

A: The plugin modifies the working copy in Sigil. Your original EPUB file on disk is unchanged until you save in Sigil (File → Save).

Q: Will this work with EPUB2 and EPUB3?

A: Yes, it works with both formats. The plugin operates on CSS, which is the same in EPUB2 and EPUB3.

Q: Can I use this on Kindle (AZW3/KFX) files?

A: No, this plugin is for Sigil, which edits EPUB files. For Kindle files, you need to:

1. Convert to EPUB using Calibre
2. Edit in Sigil with this plugin
3. Convert back to Kindle format

Technical Questions

Q: What happens to CSS comments?

A: Comments are completely preserved. The plugin:

1. Temporarily removes comments before processing
2. Stores them with unique placeholders
3. Restores them exactly after conversion

Q: Does this change my HTML structure?

A: No. Only CSS property values change. Your HTML tags, classes, IDs, and structure remain identical.

Q: What if I have both font-size and font shorthand?

A: The plugin handles both:

• Shorthand disabled: Converts only font-size:, ignores font:
• Shorthand enabled: You choose whether to convert both or just font-size:

Q: How does the plugin know what's "unsafe" for shorthand?

A: It looks for:

• CSS functions: calc(), var(), min(), max(), clamp()
• Multiple slashes (unusual line-height syntax)
• Overly complex patterns (8+ space-separated values)

These patterns can't be reliably converted with simple regex matching.

Q: Can I edit values while in the Preview window?

A: No, the preview is read-only. Close the preview, open Configuration, change values, then preview again.

Q: Does the plugin work on locked or DRM-protected EPUBs?

A: No. Sigil cannot edit DRM-protected files. Remove DRM first using appropriate tools.

Configuration Questions

Q: What's the difference between "Save as Default" and "Save to Named Config"?

A:

• Save as Default: Becomes your starting configuration every time you open the plugin
• Save to Named Config: Saves as a separate preset you can load when needed

You can have one default + multiple named configs.

Q: Where are named configurations stored?

A: In ~/.sigil/NewUnit/configs/ (Mac/Linux) or %APPDATA%/sigil/NewUnit/configs/ (Windows) as JSON files.

Q: Can I share configurations with other people?

A: Yes! Named config files are plain JSON. You can:

1. Find them in the configs folder
2. Copy to another computer
3. Place in the same folder location
4. They'll appear in "Load Named Config"

Q: Why does the plugin remember my last file selection?

A: It doesn't - file selection resets each time you open the plugin. Only the configuration (values, units, options) is saved.

Conversion Questions

Q: How do I know if conversion was successful?

A: Check:

1. Status message: "Successfully converted X match(es) in Y file(s)"
2. Console output shows each file converted
3. Open a converted file in Sigil's Code View to verify
4. Test in an e-reader to see the results

Q: Some keywords weren't converted. Why?

A: Common reasons:

• They were in unsafe shorthand patterns (check console output)
• They were in CSS comments (correctly ignored)
• They were in the wrong property (like background-size)
• You unchecked those files in the selection list

Q: Can I convert only specific keywords?

A: No, the plugin converts all 9 keywords based on the configuration. You cannot selectively enable/disable individual keywords.

Workaround: Convert all, then manually revert the ones you don't want.

Q: What if I have custom keywords or browser-specific values?

A: The plugin only handles standard CSS keywords (xx-small through larger). Custom or browser-specific keywords are not converted.

Q: Does conversion affect font families?

A: No, only the size values change. Font families (Arial, Georgia, etc.) remain unchanged.

Workflow Questions

Q: Can I run the plugin multiple times on the same book?

A: Yes, but:

• Already converted values won't be converted again
• Only remaining keywords will be found and converted
• Useful if you add new content with keywords

Q: Should I run this before or after other plugins?

A: Order usually doesn't matter. However:

• Run after plugins that add or modify CSS
• Run before plugins that analyze final formatting
• Test to find the best order for your workflow

Q: Can I convert part of a book, test it, then convert the rest?

A: Yes! Common workflow:

1. Select first 5 chapters, convert
2. Export and test in e-reader
3. If good, convert remaining chapters
4. If not, undo and adjust settings

Q: Does this work with Sigil's "Find & Replace"?

A: They're independent. This plugin is specialized for keyword conversion. For other CSS changes, use Find & Replace.

Q: What if I accidentally close the plugin after applying?

A: Undo is lost. Options:

1. Use Sigil's checkpoints to revert
2. Close without saving and reopen your EPUB
3. Restore from your backup copy
4. Re-run the plugin with inverse values (not recommended)

Troubleshooting Questions

Q: The plugin says "No files found" but I see keywords in my CSS.

A: Check:

• Are they actual font-size keywords (small, large, etc.)?
• Are they in comments only?
• Did you save changes before running the plugin?

Open Sigil's debug log to see what the plugin scanned.

Q: External backup creates files but they're empty.

A: This indicates a write permissions issue. Try:

1. Choose a different backup folder (like Desktop)
2. Check folder permissions
3. Make sure you have enough disk space

Q: How do I know which version of the plugin I have?

A: Check:

1. Window title: "CSS Font-Size Keyword Converter - Select Files v0.7.0"
2. Console output: "CSS Font-Size Keyword Converter Plugin v0.7.0"
3. Plugin Manager in Sigil shows version

Keyboard Shortcuts

The plugin uses standard Sigil/OS keyboard shortcuts:

File Selection:

• Space: Toggle checkbox focus
• Tab: Move between controls
• Enter: Click focused button

Preview/Configuration Windows:

• Ctrl/Cmd+C: Copy selected text
• Ctrl/Cmd+A: Select all text (in preview)
• Esc: Close dialog (some dialogs)

Note: No custom keyboard shortcuts are defined by the plugin.

Best Practices Summary

Do:

• Save your book before converting
• Preview changes before applying
• Test in target e-readers
• Create external backups for important books
• Save successful configurations as named presets
• Validate EPUB after conversion

Don't:

• Convert without previewing large books
• Close the plugin immediately after applying (wait to verify)
• Enable shorthand unless you understand it
• Skip testing in actual e-readers
• Forget to save your book after conversion

Quick Reference

Default Keyword Values

Button Functions

Color Codes in Preview

Version History

Version 0.7.0 (Current)

• Two-column configuration layout
• Checkbox-based file selection
• Improved shorthand safety detection
• Enhanced preview with color coding
• External backup folder validation
• Named configuration save/load
• Responsive window sizing
• Improved error messages

Contact and Support

Plugin Version: 0.7.0
Last Updated: January 2025

For issues, questions, or suggestions:

1. Check this documentation first
2. Review Sigil's debug log
3. Report issues with version info and error messages

End of User Guide